---
target: Umo Office Convert
keywords: Umo Office Convert,office在线预览,wps在线预览,docx在线预览,word在线预览,pdf在线预览
description: 将 Office、WPS 等 40 余种办公文档转换为可在线查看的文档格式，可与 Umo Office Viewer 结合使用实现办公文档的在线预览。
---

# 常见问题与故障排查

## 403 访问被拒绝（CORS）

- 现象：返回 `NotAllowed` 或 403。
- 排查：检查 `WHITE_LIST` 是否包含请求来源主机名；在非浏览器请求（curl/Postman）可允许无 `origin`。

## 转换失败（500）

- 现象：`文档转换，错误原因: ...`。
- 排查：
  - 确认文件格式受支持（扩展名与 MIME 一致）。
  - 查看磁盘权限与目录是否存在（`UPLOAD_DIR`/`CONVERTED_DIR`）。
  - 检查日志与 `X-Task-Id` 对应链路。

## 数据库连接错误 / 表初始化失败

- 现象：启动时控制台提示 `数据表创建失败`。
- 排查：
  - 检查 `DB_HOST/DB_PORT/DB_USER/DB_PASSWORD/DB_NAME`。
  - 确认 MySQL 服务已启动且网络可达。
  - 使用手动 SQL 创建数据库与授权。

## 下载原始文件失败

- 现象：`404 文件不存在` 或下载网络文件返回非 200。
- 排查：
  - 本地路径是否正确；文件是否已被清理或未保存（`UPLOAD_DIR` 未设置时可能不保存）。
  - 网络 URL 是否跨域可访问且不需要认证。

## 命中缓存但文件不一致

- 现象：`X-From-Cache: true`，但内容与预期不同。
- 排查：
  - 检查 `FILE_HASH_ALGORITHM` 与哈希计算方式是否稳定。
  - 对文件内容变化较小但哈希未变的情况进行二次校验（如增加时间戳或元数据）。

## 大文件与性能问题

- 现象：转换慢或服务卡顿。
- 排查：
  - 调整 `MAX_FILE_SIZE` 与并发数；队列化处理。
  - 升级 CPU / 内存；使用对象存储与 CDN。

## Webhook 未收到

- 现象：业务系统未收到回调。
- 排查：
  - 检查 `CONVERTED_WEBHOOK_URL` 是否正确并可公网访问。
  - 网络或防火墙策略是否阻断。

## 端口占用

- 现象：服务无法启动，提示端口已被占用。
- 排查：更换 `PORT` 或释放占用进程（PM2/其他服务）。

## 版本与依赖问题

- 建议：定期更新 Node.js、NPM 依赖版本，修复安全与兼容性问题。
